home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / LPC / modifiers < prev    next >
Text File  |  2001-06-30  |  9KB  |  178 lines
  1. CONCEPT
  2.         modifiers
  3.  
  4. DESCRIPTION
  5.         A modifier changes the syntactic and/or semantic behaviour of
  6.         an object-global variable or a function in an object.
  7.         The existing modifiers are described below.
  8.         To use a modifier just prepend it to the declaration. If several
  9.         modifiers are to be used their order does not matter:
  10.  
  11.         private int bar;                      // example for a variable
  12.         static nomask int foo() { return 3; } // example for a function
  13.  
  14.         For functions:
  15.         ~~~~~~~~~~~~~~
  16.         private   -- such functions can only be called with an internal
  17.                      call from within this file. Not even inheriting
  18.                      objects can call these functions. You can nevertheless
  19.                      build an lfun-closure with #' out of a private function.
  20.         protected -- such functions can be called from within the object,
  21.                      or from inheriting objects; but in neither case
  22.                      with call_other(). It is possible to create #' closures
  23.                      or use symbol_function() from within the object.
  24.                      Its use is preferred over the older "static".
  25.         static    -- such functions can be called from within the object
  26.                      in either way (internal call or with call_other()).
  27.                      Inheriting objects can call such functions.
  28.                      But it is not possible to call static functions from
  29.                      other objects via call_other().
  30.                      Note that an add_action() is treated like a call
  31.                      from within the object except the player who got the
  32.                      add_action() was forced (thus it is a simple way to
  33.                      secure an add_action() against forces, although this
  34.                      method has the severe disadvantages of raising an error
  35.                      at the force so better use the security system).
  36.                      Also efuns like call_out() or input_to() can call
  37.                      these functions if given as a string.
  38.         public    -- this is the default type. Such functions can be called
  39.                      from within the file as well as from inheriting objects
  40.                      and other objects via call_other().
  41.                      To declare a function public only results in the
  42.                      impossibility to change the accessibility at the
  43.                      inherit statement (see below). No error will occur,
  44.                      only the type will not be modified by the inherit
  45.                      statement.
  46.         nomask    -- such functions cannot be overridden by inheriting
  47.                      objects. If you have the fun foo() defined in your
  48.                      object and inherit an object which also has declared
  49.                      a function foo() and this nomask, you will get an
  50.                      compile error if you try to load your object.
  51.                      Furthermore a shadow will fail if it tries to shadow
  52.                      a nomask declared function.
  53.         varargs   -- this changes the syntax of the function in a way that
  54.                      not all of the arguments in the declaration must be
  55.                      given at the call. This is often very usefull if some
  56.                      of the arguments shall be omitable (the omitted
  57.                      arguments are set to 0 if the function is called with
  58.                      fewer arguments than specified).
  59.                      This is mainly within the object really necessary;
  60.                      call_other()s usually (that is if they do not have a
  61.                      certain pragma ('man pragma')) do not need the called
  62.                      function to be declared varargs to omit any arguments,
  63.                      but it is good style to use this modifier to document
  64.                      the code by this.
  65.  
  66.         For object-global variables:
  67.         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  68.         private   -- such variables can only be accessed from within the
  69.                      same object. Not even inheriting objects can access
  70.                      private variables.
  71.                      It is a good style to declare all internal variables
  72.                      private to prevent inheriting objects from accessing
  73.                      the variables directly without using functions.
  74.         nosave    -- such variables are neither stored with save_object()
  75.                      nor restored with restore_object(). This can be very
  76.                      useful if you want a room to use save_object() and
  77.                      restore_object() to save your own defined variables
  78.                      but not the hundreds of variables inherited from a
  79.                      room-class (e.g. /complex/room). You then use the modifier
  80.                      at the inherit statement (see below).
  81.                      Note that nosave and private do not overlap in any
  82.                      way. They are absolutely independant.
  83.                      The driver may be compiled to not recognize this
  84.                      keyword ('static' is then to be used). If 'nosave'
  85.                      is available, the macro __LPC_NOSAVE__ is defined.
  86.         static    -- the old name for 'nosave'. Its use is deprecated.
  87.         public    -- declares the variable public. It cannot be declared
  88.                      private or static by inheriting. No error will occur,
  89.                      only the type will not be modified by the inherit
  90.                      statement.
  91.  
  92.         It is no good style to let inheriting objects have access to
  93.         internal variables so declare them as private and offer functions
  94.         to query and change the variables if possible.
  95.  
  96.         It is also possible to redeclare all variables and/or functions
  97.         of an inherited object for the own object at the inheriting
  98.         statement:
  99.  
  100.         private functions nosave variables inherit "complex/room";
  101.         public variables inherit "complex/room";
  102.         private functions inherit "complex/room";
  103.  
  104.         To redeclare a function or a variable declared public in the
  105.         inherited object to be private or static is not possible.
  106.  
  107.         There also exists a modifier explicitly for the inherit statement:
  108.  
  109.         virtual   -- inherits the given object virtually. This only makes
  110.                      sense in a complex inherit tree.
  111.                      If an object is inherited normally (not virtually)
  112.                      twice somewhere in the inherit tree the intern
  113.                      variables exist twice. If inherited virtually they
  114.                      exist only once.
  115.                      Example:
  116.                      A inherits B and C.
  117.                      B inherits D.
  118.                      C inherits D.
  119.                      If the inheritance of D is virtual in B and C
  120.                      D's variables exist only once in A. If A changes
  121.                      D's variables via functions of B this also changes
  122.                      the variables of D as known by C.
  123.  
  124.                      virtual:               non-virtual:
  125.                         A                        A
  126.                        / \                      / \
  127.                       B   C                    B   C
  128.                        \ /                     |   |
  129.                         D                      D   D
  130.  
  131.  
  132.         To simplify the adoption of existing code, LPC allows to specify
  133.         a default visibility for functions and variables, using a syntax
  134.         similar to the inherit syntax:
  135.  
  136.           default private;
  137.             
  138.             All variables and functions are by default private.
  139.  
  140.           default private variables public functions;
  141.  
  142.             All variables are by default private, but functions are public.
  143.  
  144.         Only the modifiers 'private', 'public' and 'protected' (and 'static'
  145.         for functions only) are allowed here.
  146.  
  147.         The default visibility thus set affects only variables/functions with
  148.         no explicite visibility:
  149.  
  150.           default private;
  151.  
  152.           int private_var;
  153.           public int public_var;
  154.  
  155.         The definition is valid from the point of the 'default' statement
  156.         until the end of the file, or until the next 'default' statement:
  157.  
  158.           default private;
  159.  
  160.           int private_var;
  161.  
  162.           default public;
  163.  
  164.           int public_var;
  165.  
  166.         Note that this default visibility does not affect inherits.
  167.  
  168.  
  169. HISTORY
  170.         The modifier 'static' for variables was renamed to 'nosave'
  171.         with LDMud 3.2.8. 'static' is still recognized as an alias.
  172.  
  173.         The default visibility was added in LDMud 3.2.9 as experimental
  174.         feature.
  175.  
  176. SEE ALSO
  177.             closures(LPC), inheritance(LPC), functions(LPC), types(LPC)
  178.